CODESYS String Libraries

The libraries in the CODESYS String Libraries package can be used to process strings which are UTF-8 encoded. The basis is the IString interface from the String Segments library. Using this interface, the strings can be passed to the respective functions by reference. For example, to create an IString instance, the GSB.UTF8String function block from the Generic String Base library is provided.

The new string libraries can also handle large strings efficiently. The length of the strings is almost unlimited. For this reason, the libraries are also suitable for editing large text files and web contents.

The new string libraries let you query a previously defined string via corresponding methods, just as you know it from other high-level languages.

udiStringLen := myString.Len();
if udiStringLen = 22 THEN
...

As of CODESYS 3.5.18.0, you can set the compiler to interpret the contents of variables of type STRING as UTF-8 encoding. You select the UTF8 Encoding for STRING option in the Project Settings in the Compile options category.

If you do not want to treat all STRING variables in a project as UTF-8 encoded, the you need to clear this option. After that, you can apply UTF-8 encoding to individual literals of the STRING type on a case-by-case basis.

{attribute 'monitoring_encoding' := 'UTF-8'}
sValue : STRING(140) := UTF8#'Ðα ṧтℯ♄ ḯḉℌ ηuη, i¢ℌ αямℯґ 𝕋øґ‼ Ṳᾔⅾ ♭ḯη ＄☺ ḱℓυℊ αł＄ ωⅈ℮ ẕυ√◎ґ';

Thanks to the capabilities of UTF-8 encoding, you do not have to use the WSTRING data type in CODESYS to use an extended character set. UCS-2 encoding, which WSTRING is based on, may require more memory than a UTF-8 encoding, depending on the application. UCS-2 encoding always uses one WORD per character and can represent only the characters U+0000 to U+D800 and U+DFFF to U+FFFD. UTF-8 encoding requires between one and four bytes per character. As a result, all Unicode characters can be processed.

With UTF-8 encoding, if you try to get a specific character using a specific index, then this will lead to unexpected results due to the variable length.

{attribute 'monitoring_encoding' := 'UTF-8'}
sValue : STRING(140) := UTF8#'Ðα ṧтℯ♄ ḯḉℌ ηuη, i¢ℌ αямℯґ 𝕋øґ‼ Ṳᾔⅾ ♭ḯη ＄☺ ḱℓυℊ αł＄ ωⅈ℮ ẕυ√◎ґ';

byValue := sValue[13]; // The 'u' is NOT the 13th character in the string
xOk := byValue <> 16#75;

You need to determine the index of a character by iterating through the string.

Example 4. Iteration over UTF-8 encoded strings

VAR	
    {attribute 'monitoring_encoding' := 'UTF-8'}
    sValue : STRING(140) := UTF8#'Ðα ṧтℯ♄ ḯḉℌ ηuη, i¢ℌ αямℯґ 𝕋øґ‼ Ṳᾔⅾ ♭ḯη ＄☺ ḱℓυℊ αł＄ ωⅈ℮ ẕυ√◎ґ';

    fbsValue : STR.UTF8Literal := (psValue:=ADR(sValue)); 
    fbRange : STR.Range := (itfString:=fbsValue);
    diRune : STR.RUNE;
    udiIndex, udiLength : UDINT;
    xOk : BOOL;
END_VAR
 
WHILE (diRune := fbRange.GetNextRune(udiLength=>udiLength)) <> 0 DO
    IF diRune = 16#75 (* 'u' *) THEN
        EXIT;
    END_IF
    udiIndex := udiIndex + udiLength;
END_WHILE
 
xOk := sValue[udiIndex] = 16#75 (* 'u' *);

In the previously established STRING functions from the standard library, the parameters of type STRING are copied when they are passed to the functions. The return value is also copied to a variable with the assignment.

VAR
    sValue : STRING;
END_VAR
 
sValue := CONCAT(CONCAT(CONCAT('Da steh ich nun,', ' ich armer Tor!'), ' Und bin so'), ' klug als wie zu vor');
//                              -> Copy, LEN       -> Copy, LEN        -> Copy, LEN    -> Copy, LEN
//        -> 2xCopy, LEN
//               -> 2xCopy, LEN
//                      -> 2xCopy, LEN

Before processing the parameters of type STRING in the respective functions, their lengths often have to be determined by iteration up to the terminating null character. For longer strings, these copy and iteration operations increase the processing time of the application. The length of the strings is limited to 255 characters for the application of these functions.

The STR.IString interface was introduced to pass the data structure which manages the information about a string by reference. This is a major difference to the previously established STRING functions, which do not implement the STR.IString interface. 

Furthermore, the size of a string (the respective memory for the UTF-8 encoded characters) may be in the numeric range UDINT 4 ≦ udiSize ≦ 16#FFFF_FF00).

VAR
    itfString : STR.IString;
    udiLength, udiSize, udiRuneCount : UDINT;
    pbySegment : POINTER TO BYTE;
    xValid : BOOL;
END_VAR
 
udiLength := itfString.Len(); // Current length in byte
pbySegment := itfString.GetSegment(udiSize=>udiSize); // Address first byte, capacity of the segment in bytes
udiRuneCount := STR.RuneCount(itfString); // Current number of "characters" in the segment
xValid := itfString.IsValid(); // Indication that a valid UTF-8 encoding is present.